Introduction
Usage
Options
Conditions
Errors During Processing
Condition Syntax
Pattern Syntax
Limitations
trows is a filter for selecting lines of data that meet given conditions.
trows runs from the command line or from batch files.
Input and output data are plain ASCII text lines, each line consisting of (by default) whitespace-separated fields; see tcols for a more detailed discussion of fields and separators. Files are typically used for input and output data.
For example, consider a text file "data", containing the following table:
john 45 tennis al 31 squash tom 25 beer paul 38 women
The command:
trows from data "$2<35"
writes, to the screen, all lines whose second field is numerically less than 35:
al 31 squash tom 25 beer
Here's another example. The command:
trows from data to results "$1=/john/|$3=/women/"
copies, from "data" to a new file "results", all rows whose first field equals 'john' or whose third field equals 'women':
john 45 tennis paul 38 women
The above examples should give you an idea of what trows can do. But there's more, so read the next sections. Since trows has much in common with its sibling program tcols, you should also read tcols's documentation.
Note: All usage examples in this document are for trows running on MS-DOS. Running trows on a Unix shell requires quoting appropriate for the particular shell.
Where:
[] denotes an optional item.
Upper/lower case for the 'log', 'from', and 'to' keywords is not significant. Also, these keywords should not be used as file names.
A condition is a statement which, applied to an input line,
evaluates to either True or False.
trows copies only those lines
that meet the given conditions. Lines that contain only whitespace
are never copied.
On MS-DOS, conditions that contain '|', '<', or '>' must be surrounded
by double quotes "".
This to prevent the MS-DOS shell from treating
'<' and '>' as redirection of standard input and output, and '|' as
a pipe.
In its simplest form, a condition consists of an expression,
a comparison operator, and a second expression.
For example, in:
"$3>=/Zappa/"
$3 is the first expression, >= is the comparison operator, and /Zappa/ is the second expression.
Expressions work the same way as in tcols.
The second expression in a comparison must evaluate to exactly one string.
Now for the comparison operators. Let e and f denote expressions in the below table:
COMPARISON: TRUE IF: ----------------------------------------------------------- e=f e is equal to f. e<>f e is not equal to f. e<f e is less than f. e>f e is greater than f. e<=f e is less than or equal to f. e>=f e is greater than or equal to f.
Comparison is numerical if e and f both evaluate to integers; otherwise, comparison is ASCII-wise.
Here are some examples:
CONDITION: TRUE IF: ----------------------------------------------------------- $1=$4 1st field is equal to 4th field . "$2>25" 2nd field is greater than 25. "$l<>$3.upp" last field is not equal to 3rd field in upper case. "$1..3>76" 1st, 2nd, and 3rd field are all greater than 76. "$1..3.sum<1050" sum of 1st, 2nd, and 3rd field is less than 1050. $2..3=/hey/ both 2nd and 3rd field are both equal to hey.
Pattern matching. The general form (where e denotes an expression, and p a pattern) is:
e~/p/ whole of e matches pattern p.
Patterns must be in the form of regular expressions, as illustrated by the below table:
PATTERN: MATCHES:
-----------------------------------------------------------
a the character 'a'.
\x78 the character with ASCII code hex 78 ('x').
\+ the character '+' (escaped meta-character).
. any character.
[a-zXYZ] one of the characters a, b, ..., z, X, Y, or Z.
(character group).
[^a-zXYZ] any character but a, b, ..., z, X, Y, or Z.
(inverted character group).
abc a sequence of characters.
a* zero or more 'a's.
a+ one or more 'a's.
a? zero or one 'a's.
a|b an 'a' or a 'b'.
(ab)+ one or more occurences of the sequence 'ab'.
Here are some examples of conditions with pattern matching:
CONDITION: TRUE IF: ----------------------------------------------------------- "$1~/-?[0-9]+/" 1st field is a literal integer, possibly with a leading '-'. "$2~/a+b.*/" 2nd field begins with one or more 'a's and a 'b'. "$1..l~/.*[A-Z].*/" all fields contain an upper case letter. "$1~/.*(12|42|93)m/" 1st field ends with '12m', '42m', or '93m'.
For precise details, see the Pattern Syntax section.
Boolean operators can be used to form composite conditions. Let c and d denote conditions in the table below:
CONDITION: TRUE IF: ----------------------------------------------------------- !c c is not True. c&d c and d are True. (Note that d is not evaluated if c evaluates to False) c^d c or d, but not both, is True. Exclusive or. c|d c or d, or both, is True. (Note that d is not evaluated if c evaluates to True)
! has the highest precedence, | the lowest.
Curly brackets { } can be used to override precedence.
Here are some examples of conditions with boolean operators:
"$3=55&!{$1=/ok/&$2>8}"
$1=/jeep/&$3=45
"$2>10|$2<25"
"{$2=/ok/|$2=/allright/}&$4>=78"
If more than one condition is given, all conditions must evaluate
to True for a line to be copied.
Thus, the following two conditions:
$1=/zap/ "$2>35"
are equivalent to the one condition:
"$1=/zap/&$2>35"
Likewise, the following two conditions:
"$1=67|$2=100" "$3=44^$4=0"
are equivalent to:
"{$1=67|$2=100}&{$3=44^$4=0}"
Syntax errors in conditions will cause trows to exit with an appropriate error message, before any processing.
The Condition Syntax section describes the exact condition syntax rules.
A processing error occurs if the contents of an input line prevents trows from evaluating your condition(s).
trows's default error action is to write a relevant error message and exit. However, if you set the -w command line option, trows will skip the bad input line and continue processing the next input line. trows writes a warning anyway.
trows writes error messages and warnings to standard error (or logfile, if used).
condition ::= xorcond
| xorcond | condition
xorcond ::= andcond
| andcond ^ xorcond
andcond ::= notcond
| notcond & andcond
notcond ::= ! factor
| factor
factor ::= { condition } ; that's curly brackets
| expression = expression
| expression <> expression
| expression < expression
| expression > expression
| expression <= expression
| expression >= expression
| expression ~ / pattern /
expression ::= as for tcols
pattern ::= see below
pattern ::= or or ::= sequence | or | sequence sequence ::= closure sequence | closure closure ::= consumable * | consumable + | consumable ? | consumable consumable ::= . | char | group | ( or ) group ::= [ members ] | [ ^ members ] members ::= member members | member member ::= membchar - membchar | membchar char ::= \ any char. other than t | \t ; a tab | \n ; a newline | \xHH ; HH being two hex. digits | any char. except: ( ) | * + ? [ ] . membchar ::= \ any char. other than t and n | \t ; a tab | \n ; a newline | \xHH ; HH being two hex. digits | any char. except: - ] ^
As for tcols.